//+------------------------------------------------------------------+
//|                          Button.mqh 文本按钮控件接口类            |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
//| 依赖说明：基于 MQL5 文本控件库实现，继承自基础窗口对象类 CWndObj |
//| 核心功能：图表上的文本按钮控件，支持状态切换、外观定制、鼠标交互 |
//+------------------------------------------------------------------+
#include "WndObj.h"  // 引入基础窗口对象类（提供窗口位置、尺寸、文本等基础属性）
#include <ChartObjects/ChartObjectsTxtControls.h>  // 引入图表文本控件库（提供按钮显示能力）

//+------------------------------------------------------------------+
//| CButton 类（图表文本按钮控件）                                   |
//| 功能：MQL5 图表中的标准文本按钮，支持按下/弹起状态、锁定模式、外观定制 |
//| 继承：public CWndObj（具备窗口对象的通用能力，如位置、尺寸、文本管理） |
//| 底层依赖：通过 CChartObjectButton 实现按钮的可视化与交互逻辑       |
//+------------------------------------------------------------------+
class CButton : public CWndObj
  {
private:
   CChartObjectButton m_button;  // 底层图表文本按钮对象（核心成员，负责按钮的显示与交互）

public:
   //================================================================
   // 1. 构造与析构：按钮对象的初始化与资源清理
   //================================================================
   /**
    * @brief 构造函数：初始化按钮默认外观属性
    * @details 预设按钮文本颜色、背景色、边框色为 MQL5 控件默认值（CONTROLS_BUTTON_* 系列宏定义）
    */
                     CButton(void);

   /**
    * @brief 析构函数：清理按钮资源
    * @details 依赖父类 CWndObj 析构逻辑，自动释放窗口与底层按钮对象相关资源
    */
                    ~CButton(void);

   //================================================================
   // 2. 按钮创建：在指定图表上初始化按钮
   //================================================================
   /**
    * @brief 在图表指定位置创建文本按钮
    * @param chart [in] 目标图表ID（0 表示当前活跃图表，可通过 ChartID() 获取）
    * @param name [in] 按钮唯一标识名（图表内不可重复，用于区分不同控件）
    * @param subwin [in] 绑定的子窗口编号（0 = 主图表窗口，≥1 = 指标子窗口）
    * @param x1 [in] 按钮左上角X坐标（像素，相对于图表窗口左上角）
    * @param y1 [in] 按钮左上角Y坐标（像素）
    * @param x2 [in] 按钮右下角X坐标（像素）
    * @param y2 [in] 按钮右下角Y坐标（像素）
    * @return bool - 创建结果：true=成功（父类初始化+底层按钮创建完成），false=失败
    * @note 需先调用父类 Create 初始化窗口尺寸与位置，再创建底层 CChartObjectButton 对象
    */
   virtual bool      Create(const long chart,const string name,const int subwin,const int x1,const int y1,const int x2,const int y2);

   //================================================================
   // 3. 按钮状态控制：按下/弹起状态管理
   //================================================================
   /**
    * @brief 获取按钮当前是否处于按下状态
    * @return bool - 状态值：true=按下（ON 状态），false=未按下（OFF 状态）
    */
   bool              Pressed(void)          const { return(m_button.State()); }

   /**
    * @brief 设置按钮的按下/弹起状态
    * @param pressed [in] 目标状态：true=强制按下，false=强制弹起
    * @return bool - 操作结果：true=状态设置成功，false=失败（未绑定图表或底层对象异常）
    */
   bool              Pressed(const bool pressed)  { return(m_button.State(pressed)); }

   //================================================================
   // 4. 按钮锁定属性：控制按下状态是否保持
   //================================================================
   /**
    * @brief 获取按钮是否启用锁定模式
    * @return bool - 模式状态：true=锁定模式（按下后保持状态，需手动重置），false=普通模式（松开鼠标自动弹起）
    * @note 依赖父类 CWndObj 的 WND_PROP_FLAG_CAN_LOCK 标志位实现
    */
   bool              Locking(void)          const { return(IS_CAN_LOCK); }

   /**
    * @brief 设置按钮是否启用锁定模式
    * @param flag [in] 目标模式：true=启用锁定，false=禁用锁定
    * @note 锁定模式适用于“开关型”按钮（如“显示/隐藏指标”），普通模式适用于“触发型”按钮（如“执行回测”）
    */
   void              Locking(const bool flag);

protected:
   //================================================================
   // 5. 外观配置回调：同步父类属性到底层按钮对象
   //================================================================
   /**
    * @brief 同步按钮文本（父类 m_text）到底层按钮对象
    * @return bool - 同步结果：true=文本设置成功，false=失败
    */
   virtual bool      OnSetText(void)              { return(m_button.Description(m_text)); }

   /**
    * @brief 同步按钮文本颜色（父类 m_color）到底层按钮对象
    * @return bool - 同步结果：true=颜色设置成功，false=失败
    */
   virtual bool      OnSetColor(void)             { return(m_button.Color(m_color)); }

   /**
    * @brief 同步按钮背景色（父类 m_color_background）到底层按钮对象
    * @return bool - 同步结果：true=背景色设置成功，false=失败
    */
   virtual bool      OnSetColorBackground(void)   { return(m_button.BackColor(m_color_background)); }

   /**
    * @brief 同步按钮边框色（父类 m_color_border）到底层按钮对象
    * @return bool - 同步结果：true=边框色设置成功，false=失败
    */
   virtual bool      OnSetColorBorder(void)       { return(m_button.BorderColor(m_color_border)); }

   /**
    * @brief 同步按钮字体（父类 m_font）到底层按钮对象
    * @return bool - 同步结果：true=字体设置成功，false=失败
    */
   virtual bool      OnSetFont(void)              { return(m_button.Font(m_font)); }

   /**
    * @brief 同步按钮字体大小（父类 m_font_size）到底层按钮对象
    * @return bool - 同步结果：true=字体大小设置成功，false=失败
    */
   virtual bool      OnSetFontSize(void)          { return(m_button.FontSize(m_font_size)); }

   //================================================================
   // 6. 内部事件回调：处理按钮生命周期与交互事件
   //================================================================
   /**
    * @brief 按钮创建完成后回调（初始化底层按钮对象）
    * @return bool - 处理结果：true=底层按钮创建成功，false=失败
    */
   virtual bool      OnCreate(void);

   /**
    * @brief 按钮显示时回调（设置为在所有时间周期显示）
    * @return bool - 处理结果：true=显示设置成功，false=失败
    */
   virtual bool      OnShow(void);

   /**
    * @brief 按钮隐藏时回调（设置为不在任何时间周期显示）
    * @return bool - 处理结果：true=隐藏设置成功，false=失败
    */
   virtual bool      OnHide(void);

   /**
    * @brief 按钮位置移动时回调（更新底层按钮的坐标）
    * @return bool - 处理结果：true=位置更新成功，false=失败
    */
   virtual bool      OnMove(void);

   /**
    * @brief 按钮尺寸调整时回调（更新底层按钮的宽高）
    * @return bool - 处理结果：true=尺寸更新成功，false=失败
    */
   virtual bool      OnResize(void);

   /**
    * @brief 鼠标左键按下时回调（切换按钮状态，锁定模式下保持）
    * @return bool - 处理结果：true=事件处理完成，false=失败
    */
   virtual bool      OnMouseDown(void);

   /**
    * @brief 鼠标左键松开时回调（非锁定模式下自动弹起按钮）
    * @return bool - 处理结果：true=事件处理完成，false=失败
    */
   virtual bool      OnMouseUp(void);
  };
//+------------------------------------------------------------------+